Skip to content

Commit 8b40178

Browse files
bgn42bgn42
authored
Changed error messages for already installed versions (#647)
## Fixes - better error message for already installed versions ## Changes - checking for versioning type before showing error message ## Checklist <!-- Put an `x` in the boxes. All tasks must be completed and boxes checked before merging. --> - [x] 🤖 This change is covered by unit tests (if applicable). - [x] 🤹 Manual testing has been performed (if necessary). - [x] 🛡️ Security impacts have been considered (if relevant). - [x] 📖 Documentation updates are complete (if required). - [x] 🧠 Third-party dependencies and TPIP updated (if required).
1 parent 03aa690 commit 8b40178

File tree

2 files changed

+269
-4
lines changed

2 files changed

+269
-4
lines changed

‎CACHE_INDEX_FEATURE.md‎

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
# Cache Index Feature - Documentation for Testing
2+
3+
## Overview
4+
5+
As of the recent update, cpackget has introduced a new **cache index file**
6+
(`cache.pidx`) to improve reliability and performance when managing PDSC files.
7+
This document describes the changes and how users can test the new system.
8+
9+
## Background
10+
11+
Previously, cpackget relied on the `index.pidx` file in the `.Web` directory
12+
to retrieve information about installed PDSC files. This could lead to
13+
inconsistencies.
14+
15+
## What Changed
16+
17+
### New Cache File: `cache.pidx`
18+
19+
The major improvement is the introduction of a **cache index file** located at:
20+
21+
```text
22+
<CMSIS_PACK_ROOT>/.Web/cache.pidx
23+
```
24+
25+
This cache file maintains an accurate record of all PDSC files that are
26+
currently cached in the `.Web` directory.
27+
28+
### Key Benefits
29+
30+
1. **Improved Reliability**: The cache index accurately reflects what is
31+
actually present in the `.Web` directory, eliminating discrepancies between
32+
the public index and local cache.
33+
34+
2. **Better Performance**: Operations that check for cached PDSC files no
35+
longer need to scan the entire `.Web` directory or rely on potentially
36+
outdated information from `index.pidx`.
37+
38+
3. **Automatic Synchronization**: The cache index is automatically updated when:
39+
- PDSC files are downloaded
40+
- The public index is updated
41+
- Packs are installed or removed
42+
43+
### How It Works
44+
45+
#### Cache Initialization
46+
47+
When cpackget starts, it can initialize the cache index by scanning existing PDSC files:
48+
49+
```bash
50+
# The cache is automatically initialized when needed
51+
cpackget update-index
52+
```
53+
54+
The initialization process:
55+
56+
- Scans all `*.pdsc` files in the `.Web` directory
57+
- Extracts pack information (Vendor, Name, Version)
58+
- Reads each PDSC file to get the latest version and URL information
59+
- Builds the `cache.pidx` file with this information
60+
61+
#### Cache Updates
62+
63+
The cache is automatically maintained during:
64+
65+
- **Pack Installation**: When a pack is installed, its PDSC entry is added to the cache
66+
- **Index Updates**: When `update-index` is run, the cache is synchronized with newly downloaded PDSC files
67+
- **PDSC Downloads**: Individual PDSC file downloads update the cache accordingly
68+
69+
### File Format
70+
71+
The `cache.pidx` file uses the same XML format as `index.pidx`:
72+
73+
```xml
74+
<index schemaVersion="1.1.0">
75+
<vendor>Various</vendor>
76+
<url></url>
77+
<pindex>
78+
<pdsc url="https://www.keil.com/pack/" vendor="ARM" name="CMSIS" version="5.9.0"/>
79+
<pdsc url="https://www.keil.com/pack/" vendor="Keil" name="STM32F4xx_DFP" version="2.17.1"/>
80+
<!-- More entries... -->
81+
</pindex>
82+
</index>
83+
```
84+
85+
## Testing the New System
86+
87+
### 1. Fresh Installation Test
88+
89+
Start with a clean pack root to see the cache being built from scratch:
90+
91+
```bash
92+
# Create a new pack root
93+
cpackget init --pack-root /path/to/test-pack-root https://www.keil.com/pack/index.pidx
94+
95+
# The cache.pidx will be created automatically
96+
# Check if it exists
97+
ls /path/to/test-pack-root/.Web/cache.pidx
98+
```
99+
100+
### 2. Pack Installation Test
101+
102+
Test that the cache is correctly updated when installing packs:
103+
104+
```bash
105+
# Install a pack
106+
cpackget add ARM::CMSIS
107+
108+
# Check the cache contains the PDSC entry
109+
# On Windows:
110+
type %CMSIS_PACK_ROOT%\.Web\cache.pidx | findstr "CMSIS"
111+
# On Linux/Mac:
112+
grep CMSIS $CMSIS_PACK_ROOT/.Web/cache.pidx
113+
```
114+
115+
### 3. Index Update Test
116+
117+
Verify that updating the index properly synchronizes the cache:
118+
119+
```bash
120+
# Update the public index
121+
cpackget update-index
122+
123+
# The cache should now reflect any new PDSC files downloaded
124+
# Compare the number of entries:
125+
# - index.pidx shows all available packs
126+
# - cache.pidx shows only cached PDSC files
127+
```
128+
129+
### 4. Cache Consistency Test
130+
131+
Test the automatic cache initialization for existing installations:
132+
133+
```bash
134+
# If you have an existing pack root without cache.pidx:
135+
# Just run any command that needs the cache
136+
137+
cpackget list --public
138+
139+
# cpackget will automatically initialize the cache from existing PDSC files
140+
```
141+
142+
### 5. Error Recovery Test
143+
144+
Test how the system handles corrupted or missing cache files:
145+
146+
```bash
147+
# Delete the cache file
148+
rm $CMSIS_PACK_ROOT/.Web/cache.pidx
149+
150+
# Run a command - the cache should be automatically rebuilt
151+
cpackget update-index
152+
```
153+
154+
## Expected Behavior Changes
155+
156+
### Before (using `index.pidx`)
157+
158+
- PDSC file information could be out of sync with actual cached files
159+
160+
### After (using `cache.pidx`)
161+
162+
- PDSC cache information is always accurate
163+
- Automatic synchronization reduces manual intervention
164+
165+
## Troubleshooting
166+
167+
### Cache is Empty or Missing
168+
169+
If the `cache.pidx` file is empty or missing:
170+
171+
```bash
172+
# Force cache initialization by updating the index
173+
cpackget update-index
174+
```
175+
176+
### Cache Out of Sync
177+
178+
If you suspect the cache is out of sync:
179+
180+
```bash
181+
# Remove the cache and let it rebuild
182+
rm $CMSIS_PACK_ROOT/.Web/cache.pidx
183+
cpackget update-index
184+
```
185+
186+
### Debugging
187+
188+
Enable verbose logging to see cache operations:
189+
190+
```bash
191+
cpackget -v add ARM::CMSIS
192+
```
193+
194+
This will show:
195+
196+
- Cache reads and writes
197+
- PDSC file downloads
198+
- Cache synchronization operations
199+
200+
## Migration from Previous Versions
201+
202+
If you're upgrading from a version without the cache feature:
203+
204+
1. **Automatic Migration**: Simply run any cpackget command. The cache will
205+
be automatically created from your existing `.Web` PDSC files.
206+
207+
2. **Manual Verification**: After migration, compare your installed packs:
208+
209+
```bash
210+
cpackget list
211+
```
212+
213+
3. **No Breaking Changes**: All existing commands work the same way. The cache is an internal optimization.
214+
215+
## Technical Details
216+
217+
### File Locations
218+
219+
- Public index: `<CMSIS_PACK_ROOT>/.Web/index.pidx`
220+
- Cache index: `<CMSIS_PACK_ROOT>/.Web/cache.pidx` (NEW)
221+
- Local index: `<CMSIS_PACK_ROOT>/.Local/local_repository.pidx`
222+
223+
### Constants
224+
225+
```go
226+
const PublicIndexName = "index.pidx"
227+
const PublicCacheIndex = "cache.pidx" // NEW
228+
```
229+
230+
### API Changes
231+
232+
The changes are internal and backward compatible. No API changes affect end users.
233+
234+
## Reporting Issues
235+
236+
If you encounter any issues with the cache system:
237+
238+
1. Enable verbose logging: `cpackget -v [command]`
239+
2. Check if `cache.pidx` exists and is properly formatted
240+
3. Try rebuilding the cache by removing it and running `update-index`
241+
4. Report issues with:
242+
- Your OS and cpackget version
243+
- The command that failed
244+
- The verbose log output
245+
- The state of your `.Web` directory
246+
247+
## Summary
248+
249+
The introduction of `cache.pidx` significantly improves the performance of
250+
cpackget by maintaining an accurate record of cached PDSC files. The feature is
251+
transparent to users and requires no changes to existing workflows, while
252+
providing automatic error recovery and synchronization.
253+
254+
For most users, the transition will be seamless - the cache will be
255+
automatically created and maintained. Power users can verify cache operations
256+
using verbose logging and can manually trigger cache rebuilds when needed.

‎cmd/installer/root.go‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -162,17 +162,26 @@ func AddPack(packPath string, checkEula, extractEula, forceReinstall, noRequirem
162162
log.Debugf("Moved pack to temporary path %q", backupPackPath)
163163
dropPreInstalled = true
164164
} else {
165-
if pack.versionModifier == utils.AnyVersion {
165+
switch pack.versionModifier {
166+
case utils.AnyVersion:
166167
if len(pack.installedVersions) > 1 {
167168
log.Infof("Pack %q is already installed here: %q, versions: %s",
168169
packPath, filepath.Join(Installation.PackRoot, pack.Vendor, pack.Name), utils.VersionList(pack.installedVersions))
169170
} else {
170171
log.Infof("Pack %q is already installed here: %q",
171172
packPath, filepath.Join(Installation.PackRoot, pack.Vendor, pack.Name, pack.installedVersions[0]))
172173
}
173-
} else {
174-
log.Errorf("Pack \"%s@%s\" is already installed here: %q, use the --force-reinstall (-F) flag to force installation",
175-
packPath, pack.targetVersion, filepath.Join(Installation.PackRoot, pack.Vendor, pack.Name, pack.GetVersionNoMeta()))
174+
case utils.LatestVersion:
175+
if pack.targetVersion == "" {
176+
log.Errorf("Pack %q is already installed here: %q, use the --force-reinstall (-F) flag to force installation",
177+
packPath, filepath.Join(Installation.PackRoot, pack.Vendor, pack.Name, pack.GetVersionNoMeta()))
178+
} else {
179+
log.Errorf("Pack %q (%s) is already installed here: %q, use the --force-reinstall (-F) flag to force installation",
180+
packPath, pack.targetVersion, filepath.Join(Installation.PackRoot, pack.Vendor, pack.Name, pack.GetVersionNoMeta()))
181+
}
182+
default:
183+
log.Errorf("Pack %q is already installed here: %q, use the --force-reinstall (-F) flag to force installation",
184+
packPath, filepath.Join(Installation.PackRoot, pack.Vendor, pack.Name, pack.GetVersionNoMeta()))
176185
}
177186
return nil
178187
}

0 commit comments

Comments
 (0)